home *** CD-ROM | disk | FTP | other *** search
/ Power Programmierung 2 / Power-Programmierung CD 2 (Tewi)(1994).iso / gnu / gnulib / sipp / doc / sipp.3 < prev    next >
Encoding:
GNU Info File  |  1994-02-16  |  42.6 KB  |  1,170 lines
  1. This is Info file sipp, produced by Makeinfo-1.55 from the input file
  2. sipp.tex.
  3.  
  4.    Copyright (C) 1992 Jonas Yngvesson, Inge Wallin
  5.  
  6. 
  7. File: sipp,  Node: The bumpy shader,  Next: The planet shader,  Prev: The mask shader,  Up: Provided shaders
  8.  
  9. The bumpy shader
  10. ----------------
  11.  
  12.    `bumpy_shader()' is a not really a shader. It is a function that
  13. changes the surface normal to create the impression of a bumpy surface.
  14. The bumps are dependent on the three dimensional texture coordinates.
  15. Any other shader can be used to do the final shading calculations.
  16.  
  17.    Surface description:
  18.      typedef struct {
  19.              Shader *shader;
  20.              void   *surface;
  21.              double scale;
  22.              bool   bumpflag;
  23.              bool   holeflag;
  24.      } Bumby_desc;
  25.  
  26.    * `shader' points to the shader that should be called to do the
  27.      actual shading calculations.
  28.  
  29.    * `surface' is a pointer to the surface description that should be
  30.      used in `shader'.
  31.  
  32.    * `scale' describes how much the texture coordinates should be scaled
  33.      before applying the texture.
  34.  
  35.    * `bumpflag' and `holeflag' make it possible to flatten out half of
  36.      the bumps. If only bumpflag is TRUE only bumps "standing out" from
  37.      the surface are visible.  The rest of the surface will be smooth.
  38.      If, on the other hand, only holeflag is TRUE only bumps going
  39.      "into" the surface will be visible, thus giving the surface an
  40.      eroded look. If both flags are true, the whole surface will get a
  41.      bumpy appearance, rather like an orange.
  42.  
  43. 
  44. File: sipp,  Node: The planet shader,  Prev: The bumpy shader,  Up: Provided shaders
  45.  
  46. The planet shader
  47. -----------------
  48.  
  49.    `planet_shader()' is a somewhat specialized shader that produces a
  50. texture that resembles a planet surface. The planet is of the Tellus
  51. type with a mixture of oceans and continents.  Some of the surface is
  52. covered by semi-transparent clouds which enhances the effect greatly.
  53. On the other hand, no polar caps are provided and this decreases the
  54. realism.
  55.  
  56.    The texture is 3-dimensional, so it is possible to create cube
  57. planets or even planets with cut-out parts that still have surfaces that
  58. resemble the earth surface.  The texture is not scalable, and is
  59. designed to be used with texture coordinates in the range [-1, 1], e.g.
  60. a unit sphere. The world coordinates need not have the same order of
  61. magnitude of course .
  62.  
  63.    Surface description: The planet shader uses the same surface
  64. description as `basic_shader()', a `Surf_desc' (see *Note The basic
  65. shader::), but the colors on the surface are hard coded in the shader,
  66. so the color entry in the description is ignored.
  67.  
  68. 
  69. File: sipp,  Node: Writing your own shaders,  Prev: Provided shaders,  Up: Shaders
  70.  
  71. Writing your own shaders
  72. ========================
  73.  
  74.    As mentioned earlier, SIPP calls a shading function for every point
  75. that is rendered. To be able to perform all necessary calculations, the
  76. shader needs quite a lot of information of the state the rendering is
  77. in. All information are sent to the shader as pointers to the data used
  78. internally in SIPP. It is very important that this information is left
  79. unchanged. If any processing of the values is needed, e.g. normalization
  80. of the surface normal, the result must be stored in local variables in
  81. the shader.
  82.  
  83.    The shading functions have the following interface:
  84.      void
  85.      my_shader(world, normal, texture, view_vec, lights, surface, color, opacity)
  86.              Vector        *world;
  87.              Vector        *normal;
  88.              Vector        *texture;
  89.              Vector        *view_vec;
  90.              Lightsource   *lights;
  91.              void          *surface;
  92.              Color         *color;
  93.              Color         *opacity;
  94.  
  95.    * `world' is the position in world coordinates of the point that is
  96.      rendered.
  97.  
  98.    * `normal' is the surface normal in the point. Note: this vector is
  99.      NOT normalized.
  100.  
  101.    * `texture' contains the interpolated values of the texture
  102.      coordinates.
  103.  
  104.    * `view_vec' is a vector pointing from the rendered point at the
  105.      viewpoint, i.e. the currently active camera.
  106.  
  107.    * `lights' points to the linked list holding all lights.
  108.  
  109.    * `surface' is a pointer to a surface description, i.e. a data area
  110.      holding information specific for the rendered surface and the
  111.      shader.  The implementor of the shader decides what to put in this
  112.      area. It is the same pointer that was sent to `surface_create()'
  113.      (*Note Creating objects::).
  114.  
  115.    * `color' points to an area where the shader should place the
  116.      calculated color of the point.
  117.  
  118.    * `opacity' points to an area where the shader should place the
  119.      calculated opacity of the point.
  120.  
  121.    Since shaders are regular C functions they can be "cascaded". If one
  122. do not want to implement a complete illumination calculation but want
  123. to do some special effect, like texture or bumpmapping, the easiest way
  124. is to write a shader that only manipulates the surface color, normal or
  125. whatever, and then calls another shader, like `phong_shader()', to do
  126. the actual shading. This is the way most of the shaders provided in
  127. SIPP work (see *Note Provided shaders::).
  128.  
  129.    If one wants to implement a new shading model, things get slightly
  130. more complicated. Lightsources and possible shadows must be considered.
  131. The heart of such a shader must contain a loop over all lightsources,
  132. which are stored in a linked list. Inside this loop every lightsource is
  133. evaluated to see how much light from it that reaches the shaded point.
  134. Here is an skeleton example of how the code could look:
  135.  
  136.      void
  137.      my_shader(world, normal, texture, view_vec, lights, surface, color, opacity)
  138.          Vector        *world;
  139.          Vector        *normal;
  140.          Vector        *texture;
  141.          Vector        *view_vec;
  142.          Lightsource   *lights;
  143.          void          *surface;
  144.          Color         *color;
  145.          Color         *opacity;
  146.      {
  147.          Lightsource  *lp;            /* Current lightsource */
  148.          Vector        light_vec;     /* Direction to current lightsource */
  149.          double        light_factor;  /* Fraction of light reaching us */
  150.          Color         light_color;   /* Resulting color from lightsource */
  151.      
  152.          /*
  153.           * Other declarations and various initializations
  154.           * ...
  155.           * ...
  156.           */
  157.      
  158.          /*
  159.           * Loop over all lightsources
  160.           */
  161.      
  162.          for (lp = lights; lp != NULL; lp = lp->next)
  163.          {
  164.                  /* Find out where the lightsource are and */
  165.                  /* how much light from it that reaches us. */
  166.      
  167.                  light_factor = light_eval(lp, world, &light_vec);
  168.      
  169.                  /* Calculate contributed light from the lightsource */
  170.      
  171.                  light_color.red = light_factor * lp->color.red;
  172.                  light_color.grn = light_factor * lp->color.grn;
  173.                  light_color.blu = light_factor * lp->color.blu;
  174.      
  175.                  /*
  176.                   * Calculate shading contribution from the
  177.                   * lightsource using whatever model the shader
  178.                   * implements.
  179.                   * ...
  180.                   * ...
  181.                   */
  182.          }
  183.      
  184.          /*
  185.           * Store the final calculated color and opacity
  186.           * for the point where SIPP can find it and return.
  187.           */
  188.      
  189.          color->red = ....
  190.          color->grn = ....
  191.          color->blu = ....
  192.      
  193.          opacity->red = ....
  194.          opacity->grn = ....
  195.          opacity->blu = ....
  196.      }
  197.  
  198.    The function `light_eval()' and its parameters are described in more
  199. detail in the chapter on lightsources (see *Note Manipulating lights::).
  200.  
  201. 
  202. File: sipp,  Node: Object primitives,  Next: Future enhancements,  Prev: Shaders,  Up: Top
  203.  
  204. Object primitives
  205. *****************
  206.  
  207.    As mentioned before, SIPP only renders surfaces built up of polygons.
  208. Sometimes this is too low a level for the user to program in, so some
  209. higher level of abstraction is needed.  In the SIPP library a number of
  210. functions are provided that generate higher level objects from ordinary
  211. SIPP surfaces.  Most of them are simple geometric primitives, but some
  212. are more sophisticated such as Bezier surfaces. If other types of
  213. objects are needed the user has to build them by him/herself (*Note
  214. Creating objects::).
  215.  
  216.    Each object primitive which can be created in SIPP has an argument
  217. that describes what kind of texture coordinates should be assigned to
  218. the surface of the object. This parameter can have one of the following
  219. predefined values:
  220.  
  221.    * `NATURAL'
  222.  
  223.      This value tell SIPP to use a two dimensional mapping which is
  224.      "natural" for this particular object. It might be one of the other
  225.      available mappings or it might be something unique for the object.
  226.      The description of the functions for creating the individual
  227.      objects specifies how this mapping is done.
  228.  
  229.    * `CYLINDRICAL'
  230.  
  231.      A two dimensional mapping. The coordinates are assigned as if the
  232.      object were projected on a cylinder surrounding the object and
  233.      centered on the z-axis object. The coordinates are mapped so that
  234.      `x' goes from 0 to 1 around the base of the cylinder and `y' goes
  235.      from 0 to 1 from bottom to top on it.
  236.  
  237.    * `SPHERICAL'
  238.  
  239.      Same as `CYLINDRICAL', but the object are projected on a sphere
  240.      surrounding it instead.
  241.  
  242.    * `WORLD'
  243.  
  244.      A three dimensional mapping. The texture coordinates are the same
  245.      three dimensional coordinates as the world coordinates of the
  246.      object at creation time.
  247.  
  248.    The following objects are provided in the standard SIPP distribution.
  249. To use them, you must put the line
  250.      #include <primitives.h>
  251.    into your `C' source file.
  252.  
  253. * Menu:
  254.  
  255. * The cube object::     Creating a cube
  256. * The block object::    Creating a block
  257. * The prism object::    Creating a prism
  258. * The sphere object::   Creating a sphere
  259. * The ellipsoid object::Creating a ellipsoid
  260. * The cylinder object:: Creating a cylinder
  261. * The cone object::     Creating a cone
  262. * The torus object::    Creating a torus
  263. * The Bezier patch::    Creating a Bezier patch from function calls
  264. * The Bezier rotation curve:: Creating a Bezier surface from a rotated
  265.                         Bezier curve
  266. * The Bezier file::     Creating a Bezier patch from a data file
  267.  
  268. 
  269. File: sipp,  Node: The cube object,  Next: The block object,  Up: Object primitives
  270.  
  271. The cube object
  272. ===============
  273.  
  274.    This function creates a cube centered about the origin.
  275.  
  276.    The `NATURAL' texture mapping is similar to `CYLINDRICAL' but the
  277. `x' coordinate is not taken from projection on a cylinder but is evenly
  278. distributed around the perimeter. An odd thing in all the 2D mappings
  279. (all except `WORLD') for the cube is that the top face will have
  280. texture coordinates (0.0, 1.0) while the bottom will get (0.0, 0.0).
  281.  
  282.      Object *
  283.      sipp_cube(size, surface, shader, texture)
  284.              double   size;
  285.              void    *surface;
  286.              Shader  *shader;
  287.              int      texture;
  288.  
  289.    * `size'
  290.  
  291.      Size of the sides on the cube.
  292.  
  293.    * `surface'
  294.  
  295.      Pointer to the surface description to use when shading the cube.
  296.  
  297.    * `shader'
  298.  
  299.      Shader to use when shading the cube.
  300.  
  301.    * `texture'
  302.  
  303.      Choice of texture mapping.
  304.  
  305. 
  306. File: sipp,  Node: The block object,  Next: The prism object,  Prev: The cube object,  Up: Object primitives
  307.  
  308. The block object
  309. ================
  310.  
  311.    This function creates a rectangular block centered about the origin.
  312.  
  313.    The `NATURAL' texture mapping is similar to `CYLINDRICAL' but the
  314. `x' coordinate is not taken from projection on a cylinder but is evenly
  315. distributed around the perimeter. An odd thing in all the 2D mappings
  316. (all except `WORLD') for the block is that the top face will have
  317. texture coordinates (0.0, 1.0) while the bottom will get (0.0, 0.0).
  318.  
  319.      Object *
  320.      sipp_block(xsize, ysize, zsize, surface, shader, texture)
  321.              double   xsize, ysize, zsize;
  322.              void    *surface;
  323.              Shader  *shader;
  324.              int      texture;
  325.  
  326.    * `xsize, ysize, zsize'
  327.  
  328.      Size of the sides on the block.
  329.  
  330.    * `surface'
  331.  
  332.      Pointer to the surface description to use when shading the block.
  333.  
  334.    * `shader'
  335.  
  336.      Shader to use when shading the block.
  337.  
  338.    * `texture'
  339.  
  340.      Choice of texture mapping.
  341.  
  342. 
  343. File: sipp,  Node: The prism object,  Next: The sphere object,  Prev: The block object,  Up: Object primitives
  344.  
  345. The prism object
  346. ================
  347.  
  348.    This function creates a prism, i.e. a polygon in the x,y-plane which
  349. is extruded along the z-axis.
  350.  
  351.    The `NATURAL' texture mapping is similar to `CYLINDRICAL' but the
  352. `x' coordinate is not taken from projection on a cylinder but is evenly
  353. distributed around the perimeter. An odd thing in all the 2D mappings
  354. (all except `WORLD') for the prism is that the top face will have
  355. texture coordinates (0.0, 1.0) while the bottom will get (0.0, 0.0).
  356.  
  357.      Object *
  358.      sipp_prism(num_points, points, zsize, surface, shader, texture)
  359.              int      num_points;
  360.              Vector   points[];
  361.              double   zsize;
  362.              void    *surface;
  363.              Shader  *shader;
  364.              int      texture;
  365.  
  366.    * `num_points' Number of points defining the prism.
  367.  
  368.    * `points' Array of `num_points' points defining the prism. The
  369.      points should be given counterclockwise when looking at the prism
  370.      from above (positive Z). Only the `x' and `y' members in the
  371.      vectors are significant, the `z' member is ignored.
  372.  
  373.    * `zsize'
  374.  
  375.      Size of the prism along the z-axis.
  376.  
  377.    * `surface'
  378.  
  379.      Pointer to the surface description to use when shading the prism.
  380.  
  381.    * `shader'
  382.  
  383.      Shader to use when shading the prism.
  384.  
  385.    * `texture'
  386.  
  387.      Choice of texture mapping.
  388.  
  389. 
  390. File: sipp,  Node: The sphere object,  Next: The ellipsoid object,  Prev: The prism object,  Up: Object primitives
  391.  
  392. The sphere object
  393. =================
  394.  
  395.    This function creates a sphere centered around the origin.
  396.  
  397.    The `NATURAL' texture mapping is `SPHERICAL'.
  398.  
  399.      Object *
  400.      sipp_sphere(radius, resol, surface, shader, texture)
  401.              double   radius;
  402.              int      resol;
  403.              void    *surface;
  404.              Shader  *shader;
  405.              int      texture;
  406.  
  407.    * `radius'
  408.  
  409.      The radius of the sphere.
  410.  
  411.    * `resol'
  412.  
  413.      The sphere is tesselated into polygons. `resol' tells SIPP how
  414.      many polygons there should be around the "equator" of the sphere.
  415.  
  416.    * `surface'
  417.  
  418.      Pointer to the surface description to use when shading the sphere.
  419.  
  420.    * `shader'
  421.  
  422.      Shader to use when shading the sphere.
  423.  
  424.    * `texture'
  425.  
  426.      Choice of texture mapping.
  427.  
  428. 
  429. File: sipp,  Node: The ellipsoid object,  Next: The cylinder object,  Prev: The sphere object,  Up: Object primitives
  430.  
  431. The ellipsoid object
  432. ====================
  433.  
  434.    This function creates an ellipsoid centered around the origin.
  435.  
  436.    The `NATURAL' texture mapping is `SPHERICAL'.
  437.  
  438.      Object *
  439.      sipp_ellipsoid(xradius, yradius, zradius, resol, surface, shader, texture)
  440.              double   xradius;
  441.              double   yradius;
  442.              double   zradius;
  443.              int      resol;
  444.              void    *surface;
  445.              Shader  *shader;
  446.              int      texture;
  447.  
  448.    * `xradius, yradius, zradius'
  449.  
  450.      The radii of the ellipsoid in the principal axes directions.
  451.  
  452.    * `resol'
  453.  
  454.      The ellipsoid is tesselated into polygons. `resol' tells SIPP how
  455.      many polygons to generate around the "equator" of the ellipsoid.
  456.  
  457.    * `surface'
  458.  
  459.      Pointer to the surface description to use when shading the
  460.      ellipsoid.
  461.  
  462.    * `shader'
  463.  
  464.      Shader to use when shading the ellipsoid.
  465.  
  466.    * `texture'
  467.  
  468.      Choice of texture mapping.
  469.  
  470. 
  471. File: sipp,  Node: The cylinder object,  Next: The cone object,  Prev: The ellipsoid object,  Up: Object primitives
  472.  
  473. The cylinder object
  474. ===================
  475.  
  476.    This function creates a cylinder centered around the z-axis and the
  477. origin.
  478.  
  479.    The `NATURAL' texture mapping is `CYLINDRICAL'.
  480.  
  481.      Object *
  482.      sipp_cylinder(radius, resol, surface, shader, texture)
  483.              double   radius;
  484.              int      resol;
  485.              void    *surface;
  486.              Shader  *shader;
  487.              int      texture;
  488.  
  489.    * `radius'
  490.  
  491.      Radius of the cylinder.
  492.  
  493.    * `resol'
  494.  
  495.      The cylinder is tesselated into polygons, `resol' tells SIPP how
  496.      many polygons there should be around it.
  497.  
  498.    * `surface'
  499.  
  500.      Pointer to the surface description to use when shading the
  501.      cylinder.
  502.  
  503.    * `shader'
  504.  
  505.      Shader to use when shading the cylinder.
  506.  
  507.    * `texture'
  508.  
  509.      Choice of texture mapping.
  510.  
  511. 
  512. File: sipp,  Node: The cone object,  Next: The torus object,  Prev: The cylinder object,  Up: Object primitives
  513.  
  514. The cone object
  515. ===============
  516.  
  517.    This function creates a, possibly truncated, cone centered around the
  518. z-axis and the origin.
  519.  
  520.    The `NATURAL' texture mapping is `CYLINDRICAL'.
  521.  
  522.      Object *
  523.      sipp_cone(topradius, bottomradius, resol, surface, shader, texture)
  524.              double   topradius;
  525.              double   bottomradius;
  526.              int      resol;
  527.              void    *surface;
  528.              Shader  *shader;
  529.              int      texture;
  530.  
  531.    * `topradius, bottomradius'
  532.  
  533.      Radius of the cone at the top and bottom. If the cone should be
  534.      pointed at one of the end, specify 0 as radius.
  535.  
  536.    * `resol'
  537.  
  538.      The cone is tesselated into polygons, `resol' tells SIPP how many
  539.      polygons there should be around it.
  540.  
  541.    * `surface'
  542.  
  543.      Pointer to the surface description to use when shading the cone.
  544.  
  545.    * `shader'
  546.  
  547.      Shader to use when shading the cone.
  548.  
  549.    * `texture'
  550.  
  551.      Choice of texture mapping.
  552.  
  553. 
  554. File: sipp,  Node: The torus object,  Next: The Bezier patch,  Prev: The cone object,  Up: Object primitives
  555.  
  556. The torus object
  557. ================
  558.  
  559.    This function creates a torus centered around the z-axis and the
  560. origin.
  561.  
  562.    The `NATURAL' texture mapping is a two dimensional mapping with the
  563. `x' coordinate going around the "small" circle and the `y' coordinate
  564. going around the "large" circle.
  565.  
  566.      Object *
  567.      sipp_torus(bigradius, smallradius, res1, res2, surface, shader, texture)
  568.              double   bigradius;
  569.              double   smallradius;
  570.              int      res1;
  571.              int      res2;
  572.              void    *surface;
  573.              Shader  *shader;
  574.              int      texture;
  575.  
  576.    * `bigradius, smallradius'
  577.  
  578.      Radius of the big and small circle defining the torus, the small
  579.      circle is swept along the big one to sweep out the torus.
  580.  
  581.    * `res1, res2'
  582.  
  583.      The torus will be tesselated into `res1 x res2' polygons.  `res1'
  584.      is the number of vertices around the big circle and `rad2' is the
  585.      number of vertices around the small one.
  586.  
  587.    * `surface'
  588.  
  589.      Pointer to the surface description to use when shading the torus.
  590.  
  591.    * `shader'
  592.  
  593.      Shader to use when shading the torus.
  594.  
  595.    * `texture'
  596.  
  597.      Choice of texture mapping.
  598.  
  599. 
  600. File: sipp,  Node: The Bezier patch,  Next: The Bezier rotation curve,  Prev: The torus object,  Up: Object primitives
  601.  
  602. The Bezier patch
  603. ================
  604.  
  605.    This function creates one or more Bezier patches. All created
  606. patches in a call will belong to the same surface.
  607.  
  608.    The texture coordinates are a bit special for the Bezier patches.
  609. `CYLINDRICAL' and `SPHERICAL' coordinates are not applicable, if they
  610. are specified, SIPP will use `NATURAL' anyway. The `NATURAL' mapping is
  611. a two dimensional mapping using the surface parameters u and v, see
  612. figure below. Note that these parameters range from 0 to 1 within each
  613. patch!
  614.  
  615.    The patches are defined with a list of vertex coordinates and a set
  616. of 16 indices into that list for each patch. The following figure show
  617. in which order the indices to vertices corresponding to controlpoints
  618. for the patch should be given (and how u and v varies over the patch):
  619.        v=1  13____14____15____16
  620.              |     |     |     |
  621.              |     |     |     |
  622.              9____10____11____12
  623.              |     |     |     |
  624.              |     |     |     |
  625.              5_____6_____7_____8
  626.              |     |     |     |
  627.              |     |     |     |
  628.        v=0   1_____2_____3_____4
  629.      
  630.             u=0               u=1
  631.  
  632.      Object *
  633.      sipp_bezier_patch(num_vertex, vertex, num_patch, vx_index, resol,
  634.                        surface, shader, texture)
  635.              int      num_vertex;
  636.              Vector   vertex[];
  637.              int      num_patch;
  638.              int      vx_index[];
  639.              int      resol;
  640.              void    *surface;
  641.              Shader  *shader;
  642.              int      texture;
  643.  
  644.    * `num_vertex, vertex'
  645.  
  646.      The array `vertex' contains a list of `num_vertex' vertices.
  647.  
  648.    * `num_patch'
  649.  
  650.      The number of patches that should be defined.
  651.  
  652.    * `vx_index'
  653.  
  654.      A list of `16 * num_patch' indices into `vertex' defining the
  655.      control mesh of the patches. The vertices for each patch should be
  656.      specified in the order indicated in the figure above.
  657.  
  658.    * `resol'
  659.  
  660.      Each patch will be tesselated into `resol x resol' polygons.
  661.  
  662.    * `surface'
  663.  
  664.      Pointer to the surface description to use when shading the patches.
  665.  
  666.    * `shader'
  667.  
  668.      Shader to use when shading the patches.
  669.  
  670.    * `texture'
  671.  
  672.      Choice of texture mapping (only `NATURAL' and `WORLD' is
  673.      applicable.
  674.  
  675. 
  676. File: sipp,  Node: The Bezier rotation curve,  Next: The Bezier file,  Prev: The Bezier patch,  Up: Object primitives
  677.  
  678. The Bezier rotation curve
  679. =========================
  680.  
  681.    This function creates a surface by rotating one or more Bezier curves
  682. about the world z-axis.
  683.  
  684.    The texture coordinates are a bit special for these surfaces.
  685. `SPHERICAL' and `CYLINDRICAL' mappings are not applicable, and
  686. `NATURAL' mapping will apply to the piece of surface created by each
  687. Bezier curve separately. The `NATURAL' mapping uses the curve parameter
  688. u along each curve as `x' coordinate and goes from 0 to 1 around the
  689. perimeter of the rotational surface on the other axis
  690.  
  691.    The curves are defined with a list of vertex coordinates and a set
  692. of 4 indices into that list for each curve. The following figure show
  693. in which order the indices to vertices corresponding to controlpoints
  694. for the curve should be given.
  695.              4  u=1
  696.      z-axis   \
  697.          ^     \
  698.          |      3
  699.          |      |
  700.          |      |
  701.          |      2
  702.          |       \
  703.          |        \
  704.          |         1  u=0
  705.  
  706.      Object *
  707.      sipp_bezier_rotcurve(num_vertex, vertex, num_curve, vx_index, resol,
  708.                        surface, shader, texture)
  709.              int      num_vertex;
  710.              Vector   vertex[];
  711.              int      num_curve;
  712.              int      vx_index[];
  713.              int      resol;
  714.              void    *surface;
  715.              Shader  *shader;
  716.              int      texture;
  717.  
  718.    * `num_vertex, vertex'
  719.  
  720.      The array `vertex' contains a list of `num_vertex' vertices.
  721.  
  722.    * `num_patch'
  723.  
  724.      The number of curves that should be defined.
  725.  
  726.    * `vx_index'
  727.  
  728.      A list of `4 * num_patch' indices into `vertex' defining the
  729.      control polygon for the curves. The vertices for each curve should
  730.      be specified in the order indicated in the figure above.
  731.  
  732.    * `resol'
  733.  
  734.      Each rotational surface will be tesselated into `resol x 4*resol'
  735.      polygons, `resol' vertices along the curve and `4*resol' vertices
  736.      around the perimeter.
  737.  
  738.    * `surface'
  739.  
  740.      Pointer to the surface description to use when shading the surface.
  741.  
  742.    * `shader'
  743.  
  744.      Shader to use when shading the surface.
  745.  
  746.    * `texture'
  747.  
  748.      Choice of texture mapping (only `NATURAL' and `WORLD' is
  749.      applicable.
  750.  
  751. 
  752. File: sipp,  Node: The Bezier file,  Prev: The Bezier rotation curve,  Up: Object primitives
  753.  
  754. The Bezier file
  755. ===============
  756.  
  757.    This functions reads descriptions of Bezier patches or Bezier curves
  758. in a predefined format from a file and creates objects out of them. The
  759. file can contain a description of patches or curves, but not both. If
  760. curves are defined, a surface will be created by rotating them about the
  761. world z-axis. The file contain basically the same information as the
  762. parameters to a call to `sipp_bezier_patch()' or
  763. `sipp_bezier_rotcurve()' and texture mapping is applied in the same way
  764. as in these functions too.
  765.  
  766.    The format of the file is very simple. Please note however, that the
  767. format differs slightly from the way the data were specified in the
  768. previous two functions. This is for compatibility with older versions.
  769. The differences are noted in detail at the spots marked Diff: below.
  770.  
  771.    First in the file is a keyword defining the type of description in
  772. the file, `bezier_curves:' or `bezier_patches:'. Then follows a
  773. description of the vertices (control points). First the word
  774. `vertices:' followed by an integer number that tells how many vertices
  775. there are in the description, then the word `vertex_list:' followed by
  776. the x, y and z coordinates for each vertex. The number of vertices must
  777. be same as the number given above. This is, however, not checked for.
  778.  
  779.    If the file contains curves, the keyword `curves:' followed by the
  780. number of Bezier curves in the file is on the next line. After this
  781. line, a line with the single keyword `curve_list:' follows. Lastly, the
  782. Bezier curves themselves follow as numbers in groups of four by four.
  783. Diff: Each number is an index into the vertex list with the first index
  784. having number 1.
  785. Diff: The indices are given in the opposit order compared to
  786. `sipp_bezier_rotcurve()'.
  787.  
  788.    If the file contains patches, the format is the same with the
  789. following exceptions: The word `patches:' is substituted for `curves:',
  790. the word `patch_list:' is substituted for `curve_list:' and the indices
  791. into the vertex list are grouped 16 by 16 instead of 4 by 4.
  792. Diff: Each number is an index into the vertex list with the first index
  793. having number 1.
  794.  
  795.    Comments can be inserted anywhere in a Bezier curve/patch description
  796. file by using the hashmark character, `#'. The comment lasts to the end
  797. of the line.
  798.  
  799.    As an example of a Bezier file is here the body of a standard Newell
  800. teapot:
  801.      # Bezier curves (rotational body) for teapot body.
  802.      
  803.      bezier_curves:
  804.      
  805.      vertices: 10
  806.      vertex_list:
  807.          3.500000E-01    0.000000E+00    5.625000E-01
  808.          3.343750E-01    0.000000E+00    5.953125E-01
  809.          3.593750E-01    0.000000E+00    5.953125E-01
  810.          3.750000E-01    0.000000E+00    5.625000E-01
  811.          4.375000E-01    0.000000E+00    4.312500E-01
  812.          5.000000E-01    0.000000E+00    3.000000E-01
  813.          5.000000E-01    0.000000E+00    1.875000E-01
  814.          5.000000E-01    0.000000E+00    7.500000E-02
  815.          3.750000E-01    0.000000E+00    1.875000E-02
  816.          3.750000E-01    0.000000E+00    0.000000E+00
  817.      
  818.      curves:    3
  819.      curve_list:
  820.      
  821.        1 2 3 4
  822.      
  823.        4 5 6 7
  824.      
  825.        7 8 9 10
  826.      
  827.      #End of teapot bezier file
  828.  
  829.      Object *
  830.      sipp_bezier_file(file, resol, surface, shader, texture)
  831.              FILE    *file;
  832.              int      resol;
  833.              void    *surface;
  834.              Shader  *shader;
  835.              int      texture;
  836.  
  837.    * `file'
  838.  
  839.      An open filepointer to the file containing the descriptions.
  840.  
  841.    * `resol'
  842.  
  843.      Each rotational surface will be tesselated into `resol x 4*resol'
  844.      polygons, `resol' vertices along the curve and `4*resol' vertices
  845.      around the perimeter.
  846.  
  847.      Patches will be tesselated into `resol x resol' polygons.
  848.  
  849.    * `surface'
  850.  
  851.      Pointer to the surface description to use when shading the
  852.      surfaces.
  853.  
  854.    * `shader'
  855.  
  856.      Shader to use when shading the surfaces.
  857.  
  858.    * `texture'
  859.  
  860.      Choice of texture mapping (only `NATURAL' and `WORLD' is
  861.      applicable.
  862.  
  863. 
  864. File: sipp,  Node: Future enhancements,  Next: Reporting bugs,  Prev: Object primitives,  Up: Top
  865.  
  866. Future enhancements
  867. *******************
  868.  
  869.    SIPP is constantly under development and we often run into new
  870. interesting things that we would like to see included. Here is a small
  871. list of such things, some more realistic than others. If you feel like
  872. adding to this list, please do! Check out the chapter on bugreports
  873. (*Note Reporting bugs::) for information on how to get in touch with us.
  874.  
  875.    * More sophisticated anti-aliasing. This should not be so difficult
  876.      with the new pixel buffer.
  877.  
  878.    * User specified normals at vertices.
  879.  
  880.    * Generalized interface to lightsources, much in the same way as the
  881.      shader interface. This would allow users to design "lightsource
  882.      shaders"
  883.  
  884.    * Better support for animation.
  885.  
  886.    * Support for some more advanced object primitives, especially
  887.      patches (Hermite, NURBS, etc.)
  888.  
  889.    * Four channel output. Write out an alpha channel together with RGB.
  890.      This is troublesome if we want to stick with the ppm-format which
  891.      does not support this. Possible solutions include switching to
  892.      Utah Raster format or writing the alpha channel in a separate
  893.      pgm-file.
  894.  
  895.    * Curved surface rendering (this would mean a name change I guess...
  896.      :-) )
  897.  
  898.    * Use some sort of "virtual memory" by swapping things to disk. This
  899.      would make it possible to run SIPP on machines with braindamaged
  900.      OS and/or hardware which doesn't support real VM.
  901.  
  902.    * Front-end for reading RIB-files (Renderman Interface Bytestream).
  903.      This might not be as impossible as it may sound.
  904.  
  905.    * Store objects in a "higher order" format, and tesselate to
  906.      polygons at rendering time. This could allow generalizing the
  907.      object interface too so users could supply their own objects, with
  908.      tesselation functions.  (Yes, I have been reading the Renderman
  909.      specs...)
  910.  
  911. Contributions
  912. =============
  913.  
  914.    We are grateful for all donations of code that we can receive. We are
  915. especially looking for new primitive objects and interesting shaders.
  916.  
  917. 
  918. File: sipp,  Node: Reporting bugs,  Next: Concept index,  Prev: Future enhancements,  Up: Top
  919.  
  920. Reporting bugs
  921. **************
  922.  
  923.    We have tried to test SIPP thoroughly, but since it is constantly
  924. being developed, there are probably numerous bugs remaining, both in the
  925. source code and in the documentation.  If you find a bug in either,
  926. please send a bug report to either `jonas-y@isy.liu.se' or
  927. `ingwa@isy.liu.se'. We will try to be as quick as possible in fixing
  928. the bugs and redistributing the fixes.
  929.  
  930.    /Jonas Yngvesson & Inge Wallin
  931.  
  932. 
  933. File: sipp,  Node: Concept index,  Next: Function index,  Prev: Reporting bugs,  Up: Top
  934.  
  935. Concept index
  936. *************
  937.  
  938. * Menu:
  939.  
  940. * Sipp_bitmap:                          Sipp_bitmap.
  941. * Sipp_pixmap:                          Sipp_pixmap.
  942. * Archives:                             Archives.
  943. * Authors:                              Authors.
  944. * Basic concepts:                       Basic concepts.
  945. * basic shader:                         The basic shader.
  946. * Bezier file:                          The Bezier file.
  947. * Bezier patch:                         The Bezier patch.
  948. * Bezier rotation curve:                The Bezier rotation curve.
  949. * block object:                         The block object.
  950. * bozo shader:                          The bozo shader.
  951. * Bugs, reporting:                      Reporting bugs.
  952. * Building objects:                     Building objects.
  953. * bumpy shader:                         The bumpy shader.
  954. * Cameras and viewpoint:                Viewpoint and cameras.
  955. * cone object:                          The cone object.
  956. * Copying license:                      License information.
  957. * Creating lightsources:                Creating lights.
  958. * Creating objects:                     Creating objects.
  959. * Creating polygons and surfaces:       Creating polygons and surfaces.
  960. * cube object:                          The cube object.
  961. * cylinder object:                      The cylinder object.
  962. * Datatypes:                            Datatypes.
  963. * Distribution:                         License information.
  964. * Duplicating objects:                  Duplicating objects.
  965. * ellipsoid object:                     The ellipsoid object.
  966. * Enhancements:                         Future enhancements.
  967. * General Public License:               License information.
  968. * Geometric operations:                 Geometric operations.
  969. * Getting started:                      Getting started.
  970. * granite shader:                       The granite shader.
  971. * Hierarchies of objects:               Building objects.
  972. * Initializations:                      Initializations.
  973. * Installation:                         Installation.
  974. * Introduction:                         Top.
  975. * Library installation:                 Library installation.
  976. * license to copy SIPP:                 License information.
  977. * Lights:                               Lights.
  978. * Lightsources:                         Lights.
  979. * Lightsources, creating:               Creating lights.
  980. * Lightsources, manipulating:           Manipulating lights.
  981. * Manipulating lightsources:            Manipulating lights.
  982. * Manual installation (on-line):        Info manual installation.
  983. * Manual installation (typeset):        Typeset manual installation.
  984. * marble shader:                        The marble shader.
  985. * mask shader:                          The mask shader.
  986. * Matrix operations:                    Matrix operations.
  987. * Object primitives:                    Object primitives.
  988. * Object transformations:               Object transformations.
  989. * object, Bezier patch:                 The Bezier patch.
  990. * object, Bezier rotation curve:        The Bezier rotation curve.
  991. * object, block:                        The block object.
  992. * object, cone:                         The cone object.
  993. * object, cube:                         The cube object.
  994. * object, cylinder:                     The cylinder object.
  995. * object, ellipsoid:                    The ellipsoid object.
  996. * object, prism:                        The prism object.
  997. * object, sphere:                       The sphere object.
  998. * object, torus:                        The torus object.
  999. * Objects:                              Objects.
  1000. * Objects hierarchies:                  Building objects.
  1001. * Objects, building:                    Building objects.
  1002. * Objects, creating:                    Creating objects.
  1003. * Objects, duplicating:                 Duplicating objects.
  1004. * Phong shader:                         The Phong shader.
  1005. * planet shader:                        The planet shader.
  1006. * Polygons:                             Polygons.
  1007. * Polygons, creating:                   Creating polygons and surfaces.
  1008. * primitive object:                     Object primitives.
  1009. * prism object:                         The prism object.
  1010. * Provided shaders:                     Provided shaders.
  1011. * Rendering:                            Rendering.
  1012. * Rendering to file:                    Rendering to file.
  1013. * Rendering to in-core images:          Rendering to in-core images.
  1014. * Rendering to other devices:           Rendering to other devices.
  1015. * Reporting bugs:                       Reporting bugs.
  1016. * shader, basic:                        The basic shader.
  1017. * shader, bozo:                         The bozo shader.
  1018. * shader, bumpy:                        The bumpy shader.
  1019. * shader, granite:                      The granite shader.
  1020. * shader, marble:                       The marble shader.
  1021. * shader, mask:                         The mask shader.
  1022. * shader, Phong:                        The Phong shader.
  1023. * shader, planet:                       The planet shader.
  1024. * shader, Strauss:                      The Strauss shader.
  1025. * shader, wood:                         The wood shader.
  1026. * Shaders:                              Shaders.
  1027. * Shaders, provided:                    Provided shaders.
  1028. * shaders, writing your own:            Writing your own shaders.
  1029. * Shading functions:                    Shading functions.
  1030. * Shadows:                              Shadows.
  1031. * SIPP, what is it?:                    What is SIPP?.
  1032. * sites:                                Archives.
  1033. * sphere object:                        The sphere object.
  1034. * Strauss shader:                       The Strauss shader.
  1035. * Surface descriptions:                 Surface descriptions.
  1036. * Surfaces:                             Surfaces.
  1037. * Surfaces, creating:                   Creating polygons and surfaces.
  1038. * Texture coordinates:                  Texture coordinates.
  1039. * texture mapping, types of:            Object primitives.
  1040. * torus object:                         The torus object.
  1041. * Transformations:                      Transformations.
  1042. * Transformations, applying:            Object transformations.
  1043. * Vector operations:                    Vector operations.
  1044. * Viewpoint and cameras:                Viewpoint and cameras.
  1045. * Virtual cameras:                      Viewpoint and cameras.
  1046. * What is SIPP?:                        What is SIPP?.
  1047. * wood shader:                          The wood shader.
  1048. * writing shaders:                      Writing your own shaders.
  1049.  
  1050. 
  1051. File: sipp,  Node: Function index,  Prev: Concept index,  Up: Top
  1052.  
  1053. Function index
  1054. **************
  1055.  
  1056. * Menu:
  1057.  
  1058. * basic_shader():                       The basic shader.
  1059. * bozo shader:                          The bozo shader.
  1060. * bumpy_shader():                       The bumpy shader.
  1061. * camera_create():                      Viewpoint and cameras.
  1062. * camera_destruct():                    Viewpoint and cameras.
  1063. * camera_focal():                       Viewpoint and cameras.
  1064. * camera_look_at():                     Viewpoint and cameras.
  1065. * camera_params():                      Viewpoint and cameras.
  1066. * camera_position():                    Viewpoint and cameras.
  1067. * camera_up():                          Viewpoint and cameras.
  1068. * camera_use():                         Viewpoint and cameras.
  1069. * granite_shader():                     The granite shader.
  1070. * light_active():                       Manipulating lights.
  1071. * light_color():                        Manipulating lights.
  1072. * light_destruct():                     Creating lights.
  1073. * light_eval():                         Manipulating lights.
  1074. * lightsource_create():                 Creating lights.
  1075. * lightsource_put():                    Manipulating lights.
  1076. * MakeVector():                         Vector operations.
  1077. * marble_shader():                      The marble shader.
  1078. * mask_shader():                        The mask shader.
  1079. * mat_mirror_plane():                   Matrix operations.
  1080. * mat_mul():                            Matrix operations.
  1081. * mat_rotate():                         Matrix operations.
  1082. * mat_rotate_x():                       Matrix operations.
  1083. * mat_rotate_y():                       Matrix operations.
  1084. * mat_rotate_z():                       Matrix operations.
  1085. * mat_scale():                          Matrix operations.
  1086. * mat_translate():                      Matrix operations.
  1087. * MatCopy():                            Matrix operations.
  1088. * object_add_subobj():                  Building objects.
  1089. * object_add_surface():                 Building objects.
  1090. * object_clear_transf():                Object transformations.
  1091. * object_create():                      Building objects.
  1092. * object_deep_dup():                    Duplicating objects.
  1093. * object_delete():                      Building objects.
  1094. * object_dup():                         Duplicating objects.
  1095. * object_get_transf():                  Object transformations.
  1096. * object_instance():                    Duplicating objects.
  1097. * object_move():                        Object transformations.
  1098. * object_rot():                         Object transformations.
  1099. * object_rot_x():                       Object transformations.
  1100. * object_rot_y():                       Object transformations.
  1101. * object_rot_z():                       Object transformations.
  1102. * object_scale():                       Object transformations.
  1103. * object_set_transf():                  Object transformations.
  1104. * object_sub_subobj():                  Building objects.
  1105. * object_sub_surface():                 Building objects.
  1106. * object_transform():                   Object transformations.
  1107. * phong_shader():                       The Phong shader.
  1108. * planet_shader():                      The planet shader.
  1109. * point_transform():                    Matrix operations.
  1110. * polygon_push():                       Creating polygons and surfaces.
  1111. * render_field_file():                  Rendering to file.
  1112. * render_field_func():                  Rendering to other devices.
  1113. * render_image_file():                  Rendering to file.
  1114. * render_image_func():                  Rendering to other devices.
  1115. * sipp_background():                    Initializations.
  1116. * sipp_bezier_file():                   The Bezier file.
  1117. * sipp_bezier_patch():                  The Bezier patch.
  1118. * sipp_bezier_rotcurve():               The Bezier rotation curve.
  1119. * sipp_bitmap_create():                 Sipp_bitmap.
  1120. * sipp_bitmap_destruct():               Sipp_bitmap.
  1121. * sipp_bitmap_line():                   Sipp_bitmap.
  1122. * sipp_bitmap_write():                  Sipp_bitmap.
  1123. * sipp_block():                         The block object.
  1124. * sipp_block():                         The block object.
  1125. * sipp_cone():                          The cone object.
  1126. * sipp_cube():                          The cube object.
  1127. * sipp_cube():                          The cube object.
  1128. * sipp_cylinder():                      The cylinder object.
  1129. * sipp_ellipsoid():                     The ellipsoid object.
  1130. * sipp_init():                          Initializations.
  1131. * sipp_pixmap_create():                 Sipp_pixmap.
  1132. * sipp_pixmap_destruct():               Sipp_pixmap.
  1133. * sipp_pixmap_set_pixel():              Sipp_pixmap.
  1134. * sipp_pixmap_write():                  Sipp_pixmap.
  1135. * sipp_prism():                         The prism object.
  1136. * sipp_prism(0:                         The prism object.
  1137. * sipp_shadows():                       Initializations.
  1138. * sipp_show_backfaces():                Initializations.
  1139. * sipp_sphere():                        The sphere object.
  1140. * sipp_sphere():                        The sphere object.
  1141. * sipp_torus():                         The torus object.
  1142. * spotlight_at():                       Manipulating lights.
  1143. * spotlight_create():                   Creating lights.
  1144. * spotlight_opening():                  Manipulating lights.
  1145. * spotlight_pos():                      Manipulating lights.
  1146. * spotlight_shadows():                  Manipulating lights.
  1147. * strauss_shader():                     The Strauss shader.
  1148. * surface_basic_create():               Creating polygons and surfaces.
  1149. * surface_basic_shader():               Creating polygons and surfaces.
  1150. * surface_create():                     Creating polygons and surfaces.
  1151. * surface_set_shader():                 Creating polygons and surfaces.
  1152. * transf_mat_create():                  Matrix operations.
  1153. * Transf_mat_destruct():                Matrix operations.
  1154. * VecAdd():                             Vector operations.
  1155. * VecAddS():                            Vector operations.
  1156. * VecComb():                            Vector operations.
  1157. * VecCopy():                            Vector operations.
  1158. * VecCross():                           Vector operations.
  1159. * VecDot():                             Vector operations.
  1160. * VecLen():                             Vector operations.
  1161. * VecNegate():                          Vector operations.
  1162. * vecnorm():                            Vector operations.
  1163. * VecScalMul():                         Vector operations.
  1164. * VecSub():                             Vector operations.
  1165. * vertex_push():                        Creating polygons and surfaces.
  1166. * vertex_tx_push():                     Creating polygons and surfaces.
  1167. * wood_shader():                        The wood shader.
  1168.  
  1169.  
  1170.